The USBEnet folder contains sample code for a USB Ethernet driver based on the use of the Apple EnetShimLib and the Apple Enet DLPI Support files. The developer focues on implementing the USB setup and data transfer routines between the device and the driver, and make use of some simple API calls to setup the transfer of data with Open Transport.
Description
The driver sample requires three working pieces of code. The Apple Enet DLPI Support port configuration code, the Apple EnetShimLib and a USB driver file. The developer implements the USB driver file. The Apple Enet DLPI Support file provides the Port Scanner code so that the USB Ethernet device will be properly registered with Open Transport when it is connected, or unregistered/made offline when the device is hot unplugged. This file also provides the port configuration routines so that a connection can be properly plumbed with OT.
The EnetShimLib code provides the means for the USB device driver to register itself with Open Transport so that if the device is selected as the port for networking services, Open Transport will know how to communicate with the device.
At startup, the Apple Enet DLPI Support code registers a notification routine watching for the attachment of USBCommClass devices with a subClass of Ethernet Control Model (6). When such a device is attached, USB will match the device to it's driver. Assuming the driver is matched, a NameRegistry entry is made for the device. The driver will perform the device configuration and when successfully completed, the driver will register itself with the EnetShimLib. In this sample code, this is handled in the call - InstallShimDrvr. The LoadShim call is made to find the entry points to the EnetShimLib, EnetShimInstallDriver, EnetShimRemoveDriver, and EnetShimAsyncStatus. After these entry points are found, a call is made to the EnetShimInstallDriver entry point, where the port is registered with Open Transport. At this time, the user may enter the AppleTalk or TCP/IP Control Panels and select the USB Enet device as the port to establish network connections through. When a network process is activated over the port, then the EnetShimLib locates and calls the EnetHAL_Entry point which the USB driver must have exported.
The EnetHAL_Open call is made at task time when the driver is opened. At this time, memory allocation can be safely made.
The EnetHAL_Start call is made when network communications are to be established. the driver is passed the Interrupt Service Routine address to call, when an incoming packet is recieved. The driver should now start the packet reception code.
The EnetHAL_Stop call is made to tell the driver to stop processing packets.
The EnetHAL_Read call is made to process incoming packets which the ISR does not process. In this case, process the first available packet.
The EnetHAL_Write call is made to send a packet onto the network.
The EnetHAL_GetMACAddress is made to retrieve the current ethernet address associated with the device.
The EnetHAL_SetMACAddress call is made to set the current ethernet address for the device. You can return an error if this functionality is not supported.
The EnetHAL_SetMulticastFilters call is made to define which Multicast packets will be handled by the device.
for each of the above calls, the sample code demonstrates how the fields of the USBEnet structure are used.
Building the Code
This sample was built using the Metrowerks CodeWarrior Pro 5, IDE version 4.0 environment and Mac OS USB DDK version 1.4.6 or pre=release. Also required are Universal Interfaces and Libraries 3.3.1 or newer. Later versions of these tools can also be used: consult the Mac OS USB DDK Readme file to determine which version of Universal Interfaces and Libraries to use. This driver is designed to be compatible with Mac OS USB releases back to version 1.2, HOWEVER, the components which the driver requires, the EnetShimLib, and the Apple Enet USB, are only being qualified for use in the presence of Mac OS USB 1.4.6 or greater.
This sample class driver is designed for use as vendor specific. If you try to make the driver, you will encounter an error for the definition of the kUSBVendorID and for the kUSBProductID. Replace these values with those that are specific for your device. Note that the driver descrioption also has the kUSBDoNotMatchGenericDevice bit set in the "Driver Loading Info" field.
To rebuild the project, place the USBEnet folder into the USBDDK:Examples: folder. The CodeWarrior project file assumes certain project-specific access paths. The resulting class driver, USBEthernetSample is placed into the USBDDK:Extensions-MCWBuilt: folder.
Bug Reports:
If you find any bugs, please send them to "usb@isg.apple.com".
Questions:
For any questions which you may have with this sample or with Mac OS USB, please submit them to either the Mac OS USB Developer mailing list, usb@isg.apple.com, or to Apple Worldwide Developer Technical Support (WWDTS), dts@apple.com. If you are not familiar with the WWDTS support plans, please check them out at the Developer Programs web page,
<http://developer.apple.com/programs/>.
To subscribe to the Mac OS USB Developer mailing list, send an email to usb@isg.apple.com with the subject set to "subscribe".
